Inside Macintosh: QuickDraw GX Graphics /

Chapter 4 - Geometric Operations / Geometric Operations Reference

Functions / Reducing and Simplifying Shapes

GXReduceShape

You can use the GXReduceShape function to remove unnecessary geometric points from a polygon or path contour.

void GXReduceShape(gxShape target, long contour);

target

A reference to the polygon or path shape containing the contour whose unnecessary geometric points you want to eliminate.

contour

The index of the contour you want to reduce. You may specify a value of 0 for this parameter to indicate all contours.

DESCRIPTION

The GXReduceShape function removes unnecessary geometric points from the contour indicated by the contour parameter of the shape indicated by the target parameter. The geometric points removed by this function include both duplicate and colinear geometric points. Duplicate geometric points are sequential geometric points in the same contour with the same (x, y) coordinate pair. Colinear geometric points are sequential geometric points that fall on the same line as the preceding and the subsequent geometric point. Although this function may affect the geometry of a shape, the resulting shape appears the same as the original shape when drawn, unless the curve error of the target shape is nonzero.

Note

Under certain circumstances, the GXReduceShape function actually increases the number of geometric points used to define a shape. For path shapes, the number of geometric points in the resulting shape can be up to one third more than the number of points in the original shape. Even in this case, the resulting shape appears the same as the original shape when drawn.

The GXReduceShape function does consider the curve error of the target shape when selecting which geometric points to remove. If the distance between a point and a neighboring point is less than that indicated by the curve error, the GXReduceShape function considers them to be duplicate points. If you specify a target shape with a nonzero curve error, the resulting shape may draw differently than the original shape--the greater the curve error, the more drastic the difference may be. For shapes with many points within a distance of less than that indicated by the curve error, the resulting shape can sometimes degenerate to a surprising result.

The shape fill of the target shape can also affect the results of this function. For example, if the first point and the last point of a contour are the same geometric point, this function removes the last point if the target shape has a closed-frame fill or any of the solid fills. However, if the target shape has an open-frame fill, this function does not remove the last point.

Similarly, if one or more of the points at the end of a contour is colinear with one or more points at the beginning of that contour, this function considers them all to lie on the same line if the target shape has a closed-frame fill or any of the solid fills and the unnecessary points are removed--even the first and last point of the original contour can be removed. However, if the target shape has an open-frame fill, the first and the last points of a contour are never removed.

This function operates only within individual contours; it never combines contours or compares points from different contours. Also, this function does not convert between shape types. The resulting shape always has the same shape type as the original shape.

If you specify a source shape that is not a polygon or a path shape, this function posts the error graphic_type_cannot_be_reduced.

If you provide a target shape that is not one of the geometric shape types, this function performs the actions described in the following table:

Shape type	Action taken
bitmap	Posts the error graphic_type_cannot_be_reduced
picture	Posts the error graphic_type_cannot_be_reduced
text	Posts the error graphic_type_cannot_be_reduced
glyph	Posts the error graphic_type_cannot_be_reduced
layout	Posts the error graphic_type_cannot_be_reduced

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
shape_is_nil
size_of_path_exceeds_implementation_limit
number_of_points_exceeds_implementation_limit
graphic_type_cannot_be_reduced	(debugging version)
Warnings
unable_to_traverse_open_contour_that_starts_or_ends_off_the_curve
	(debugging version)
contour_out_of_range
shape_access_not_allowed

SEE ALSO

For examples using this function, see "Eliminating Unnecessary Geometric Points" beginning on page 4-30.

For more information about reduced and simplified shapes, see "Reducing and Simplifying Shape Geometries" beginning on page 4-9.

For a discussion of geometric points and contours, see Chapter 2, "Geometric Shapes," in this book.

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help